/*
 * File:    DynamicThread.java
 * Created: 11-Jun-2007
 *
 * by Kenji Hollis <kenji@bitgatesoftware.com>
 * Released under the Creative Commons License version 2.5
 */

package com.bitgate.util.threads;

/**
 * This interface is used to create a dynamically controllable threading system.  It allows a reentrant function to be able to
 * control the thread by determining its process load, its running state, and control to shut the thread down programatically.
 * 
 * @author Kenji Hollis &lt;kenji@bitgatesoftware.com&gt;
 * @since 0.1
 */
public interface DynamicThread extends Runnable
{
	/** This is the thread load of the currently executing thread. */
	public enum DynamicThreadLoad {
		
		/** Indicates the thread is sleeping or doing nothing. */
		IDLE,
		
		/** Indicates the thread is running normally. */
		NORMAL,
		
		/** Indicates the thread is under heavy load, and may be at its maximum. */
		HIGH
	}
	
	/** 
	 * This is a constructor call to the underlying class that implements this interface.  This could have been a <code>Factory</code>
	 * class, but because the factory would not have been flexible enough to determine the type of factory to instantiate, this
	 * is the "next best thing" for this class.  I may refactor this later.
	 * 
	 * @return <code>DynamicThread</code> instance that can be added to a <code>Thread</code> group.
	 */
	DynamicThread newInstance();
	
	/**
	 * This allows the programmer to send a message to the running dynamic thread.
	 * 
	 * @param object An <code>Object</code>.
	 */
	void sendObject(Object object);
	
	/**
	 * Tells the current thread to shut down.
	 */
	void shutdown();
	
	/**
	 * Determines whether or not the current thread is running.
	 * 
	 * @return <code>true</code> if the thread is running, <code>false</code> otherwise.
	 */
	boolean isRunning();
	
	/**
	 * Determines the processing load of the currently running thread.
	 * 
	 * @return <code>DynamicThreadLoad</code> indicating the current thread load.
	 */
	DynamicThreadLoad getBusyState();
}